/*
 * Copyright 2002-2006 the original author or authors. Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
 * either express or implied. See the License for the specific language governing permissions and limitations under the
 * License.
 */
package pikes.xml;

import pikes.core.Printable;

/**
 * Visitor interface to process the XML document's content tree. It provides methods to react when certain elements of
 * the XML document tree are visited. The order of method calls is the following:
 * <ol>
 * <li>{@link #xmlDeclaration(CharSequence)} or {@link #xmlDeclaration(CharSequence,CharSequence)}</li>
 * <li>{@link #publicDocType(CharSequence,CharSequence,CharSequence)}, if there is a public doc type defined in the
 * XMLDocument</li>
 * <li>{@link #openingFirstTag(CharSequence)} for any XML tag</li>
 * <li>{@link #attribute(CharSequence,CharSequence)} for each attribute of the XML tag</li>
 * <li>{@link #closingFirstTag(CharSequence,boolean)} for the XML tag</li>
 * <li>If the XML tag has child content, then all children are visited in the order they were added to the parent tag.</li>
 * <li>{@link #closeSecondTag(CharSequence)}, if the XML tag has child content</li>
 * </ol>
 * @author Peter Bona
 */
public interface XMLVisitor {

	/**
	 * This method is called first when a XMLDocument is processed via {@link XMLDocument#visit(XMLVisitor)}.
	 * @param version XML version
	 * @throws XMLVisitingException
	 */
	void xmlDeclaration(CharSequence version) throws XMLVisitingException;

	/**
	 * This method is called first when a XMLDocument is processed via {@link XMLDocument#visit(XMLVisitor)}.
	 * @param version XML version
	 * @param decoding Decoding of the document
	 * @throws XMLVisitingException
	 */
	void xmlDeclaration(CharSequence version, CharSequence decoding) throws XMLVisitingException;

	/**
	 * This method is called when a public doc type definition is encountered after the XML declaration.
	 * @param name Name of the root element
	 * @param id The id of the doc type
	 * @param uri URI of the doc type
	 * @throws XMLVisitingException
	 */
	void publicDocType(CharSequence name, CharSequence id, CharSequence uri) throws XMLVisitingException;

	/**
	 * This method is called when an XML tag is visited.
	 * @param name The tag's name
	 * @throws XMLVisitingException
	 */
	void openingFirstTag(CharSequence name) throws XMLVisitingException;

	/**
	 * This method is called when an XML tag is visited.
	 * @param prefix The tag's prefix
	 * @param name The tag's name
	 * @throws XMLVisitingException
	 */
	void openingFirstTag(CharSequence prefix, CharSequence name) throws XMLVisitingException;

	/**
	 * This method is called after the XML tag's have been visited.
	 * @param name The tag's name
	 * @param hasChildren True if the tag has children content, false if it does not have.
	 * @throws XMLVisitingException
	 */
	void closingFirstTag(CharSequence name, boolean hasChildren) throws XMLVisitingException;

	/**
	 * This method is called after the XML tag's children (if there is any) have been visited. Not called if there were
	 * no children to visit.
	 * @param name The tag's name
	 * @throws XMLVisitingException
	 */
	void closeSecondTag(CharSequence name) throws XMLVisitingException;

	/**
	 * This method is called for each attribute of the XML tag is visited.
	 * @param name The key of the attribute
	 * @param value The value of the attribute
	 * @throws XMLVisitingException
	 */
	void attribute(CharSequence name, CharSequence value) throws XMLVisitingException;

	void attribute(CharSequence name, Printable value) throws XMLVisitingException;

	/**
	 * This method is called for character data.
	 * @param text The character data
	 * @throws XMLVisitingException
	 */
	void text(CharSequence text) throws XMLVisitingException;

	void text(Printable printable) throws XMLVisitingException;

	/**
	 * This method is called for XML comment.
	 * @param comment The comment text
	 * @throws XMLVisitingException
	 */
	void comment(CharSequence comment) throws XMLVisitingException;

}
